Skip to content

Add a documentation page with auto-generated screenshots#4

Merged
benzwick merged 1 commit into
mainfrom
feature/docs
May 26, 2026
Merged

Add a documentation page with auto-generated screenshots#4
benzwick merged 1 commit into
mainfrom
feature/docs

Conversation

@benzwick

Copy link
Copy Markdown
Owner

Summary

Adds a dedicated documentation site at /docs/, built as a second Vite entry alongside the app and deployed to the same GitHub Pages site. It documents every feature, explains the philosophy/origin, embeds always-current Playwright screenshots, and adds doc-linked tooltips throughout the app.

  • Docs page (docs/index.html, src/docs/): 14 sections covering all 5 tabs, the goal bar + controls, theming, CSV/JSON import, the Talk2View assistant, and a from-the-code walkthrough of both the assignment and scheduling algorithms. Includes a philosophy section on the whiteboard origin of the method at Talk2View Pty Ltd, a sticky numbered TOC, theme toggle, and deep-link anchors.
  • Auto-generated screenshots: a Playwright spec (tests/e2e/screenshots/docs.screenshots.ts) reuses the existing e2e fixtures/seeds to drive the live app (demo project, frozen clock so schedule views fill, real fonts) and writes 13 PNGs into public/screenshots/. The deploy workflow regenerates them before vite build so the docs never drift from the deployed UI. Best-effort (continue-on-error), gitignored, regenerable via npm run screenshots.
  • Shared theme module (src/ui/theme.jsx): theme machinery, colours, style objects, and Pill/Slider/SectionHead extracted out of App.jsx so both entries share them — keeping the docs bundle lean (~30 kB). Pure refactor, no behavior change.
  • Doc-linked tooltips (src/ui/Tooltip.jsx): every tab, header control, primary action button, and the schedule view switcher gets a tooltip with a description + a "Learn more →" deep link into the matching /docs/ section. Header and footer link to the docs.

Notes

  • Branched off the latest main (scheduling, CSV import, and the e2e harness already merged). The screenshot pipeline plugs into the existing Playwright harness rather than duplicating it; the import section covers CSV + JSON; the license section reflects CC0 1.0.
  • The screenshot spec lives outside the e2e testDir and uses its own config, so npm run test:e2e never runs it.

Test plan

  • npm run build produces dist/docs/index.html and dist/screenshots/*.png (13 images)
  • npm run screenshots runs green (6 tests) and writes to public/screenshots/
  • /docs/ renders with app theming/fonts; TOC + deep-link anchors scroll correctly
  • In-app tooltips show description + working "Learn more →" links; docs button in header/footer
  • CI deploy regenerates screenshots and serves joy-matrix.com/docs/

Introduces a dedicated documentation site at /docs/, built as a second Vite
entry point alongside the app and deployed to the same GitHub Pages site. It
documents every feature — the matrix, team, tasks, schedule, and insights tabs,
the goal bar and global controls, theming, CSV/JSON import, and the Talk2View
assistant — plus a from-the-code walkthrough of the two algorithms (quadrant
weights, capacity budget, and burnout thresholds for assignment; slot scoring
and energy/concentration matching for scheduling). A philosophy section records
where the method came from: the Eisenhower matrix the team kept drawing on paper
and whiteboards while running internal projects at Talk2View Pty Ltd, and the
annotations about who would enjoy, be good at, and have room for each task that
grew into the pleasure/talent/capacity model.

Every screenshot on the page is generated by Playwright rather than captured by
hand. A spec under tests/e2e/screenshots reuses the existing e2e fixtures and
seeds to drive the live app — seeding the demo project, freezing the clock so
the schedule sub-views fill with real blocks, and loading the real fonts — then
writes thirteen PNGs into public/screenshots/. The deploy workflow regenerates
them before `vite build` (which copies them into dist/screenshots/), so the
documentation never drifts out of date with the deployed UI. The capture step
is best-effort: a transient failure degrades the docs to graceful placeholders
rather than blocking the site deploy. The screenshots are gitignored and can be
regenerated locally with `npm run screenshots`; the spec lives outside the e2e
testDir and uses its own config, so `npm run test:e2e` never runs it.

To let the docs reuse the app's exact look without bundling the whole
application, the theme machinery, colour and style objects, and the small
Pill/Slider/SectionHead primitives move out of App.jsx into a shared
src/ui/theme.jsx that both entries import. The documentation page wraps that
module in the real ThemeProvider, so theme presets, dark mode, and font choices
carry across and persist via the same storage key.

Finally, every primary control in the app — the five tabs, the header buttons,
the add-member/task/category/stakeholder actions, and the schedule view switcher
— gains a tooltip (src/ui/Tooltip.jsx) that pairs a one-line description with a
"Learn more" link deep into the matching /docs/ section, and the header and
footer gain a direct link to the documentation.
@benzwick
benzwick merged commit 810ced9 into main May 26, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant